##############################################################################
# ls 命令速查表 (ls Command Cheatsheet)
# 用于列出目录内容 (List directory contents)
# https://github.com/funnyzak/cli-cheatsheets
##############################################################################

# 图例 (Legend - for `ls -l` output):
#   [文件类型与权限] [硬链接数] [所有者] [所属组] [大小(字节)] [最后修改日期 时间] [文件名]
#   drwxr-xr-x  2 user group  4096 Jul 10 10:30 directory_name
#   -rw-r--r--  1 user group 12345 Jul 10 10:31 file_name.txt
#   lrwxrwxrwx  1 user group    15 Jul 10 10:32 link_name -> target
#
#   文件类型 (权限字符串的第一个字符):
#     - : 普通文件 (Regular file)
#     d : 目录 (Directory)
#     l : 符号链接 (Symbolic link)
#     c : 字符设备文件 (Character device)
#     b : 块设备文件 (Block device)
#     s : 套接字文件 (Socket)
#     p : 命名管道 (Named pipe/FIFO)

##############################################################################
# 基本用法 (Basic Usage)
##############################################################################

ls [选项] [文件或目录...]             # 列出指定目录 (默认当前目录 .) 或文件的信息
ls                                      # 列出当前目录的内容
ls /path/to/directory                   # 列出指定路径下的内容
ls file1.txt directory1                 # 列出指定文件和目录的信息/内容

##############################################################################
# 格式化输出 (Formatting Output)
##############################################################################

ls -l                                   # 使用长格式列出 (显示详细信息: 权限, 所有者, 大小, 修改时间等)
ls -lh                                  # 长格式，并以易读方式显示文件大小 (例如 K, M, G)
ls -1                                   # 每行只列出一个文件 (单列输出)
ls -m                                   # 用逗号分隔条目，横向填充宽度
ls -F                                   # 在条目后追加文件类型指示符 (*/ => @ |)
ls -p                                   # 对目录追加 / 指示符 (类似 -F 但仅对目录)
ls --color[=WHEN]                       # 控制彩色输出 (WHEN: auto, always, never), 通常默认为 auto
ls --full-time                          # 显示完整的修改时间 (年-月-日 时:分:秒.纳秒 时区)
ls -o                                   # 类似 -l，但不显示组信息
ls -g                                   # 类似 -l，但不显示所有者信息 (在某些系统上)
ls -G                                   # (GNU) 类似 -l，但不显示组信息

##############################################################################
# 显示特定文件 (Filtering & Showing Specific Files)
##############################################################################

ls -a                                   # 列出所有文件，包括以 . 开头的隐藏文件 (包括 . 和 ..)
ls -A                                   # 列出除 . 和 .. 之外的所有文件 (常用)
ls -d [目录名]                          # 列出目录本身的信息，而不是其内容 (常用于查看目录权限)
ls -d */                                # 仅列出当前目录下的子目录本身 (配合通配符)
ls *.txt                                # 列出所有以 .txt 结尾的文件 (使用 Shell 通配符)
ls -I PATTERN                           # (GNU) 不列出匹配 PATTERN 的条目

##############################################################################
# 排序输出 (Sorting Output)
##############################################################################

ls -t                                   # 按修改时间排序，最新的在前
ls -S                                   # 按文件大小排序，最大的在前
ls -X                                   # 按扩展名排序
ls -v                                   # 按版本号自然排序 (例如 file-1.txt, file-2.txt, file-10.txt)
ls -U                                   # 不排序，按目录原有顺序显示 (通常是最快的)
ls -r                                   # 反转当前的排序顺序 (可与其他排序选项组合)

# 常用排序组合:
ls -lt                                  # 长格式，按修改时间排序 (最新在前)
ls -lS                                  # 长格式，按大小排序 (最大在前)
ls -ltr                                 # 长格式，按修改时间反向排序 (最旧在前，常用于查看日志文件)

##############################################################################
# 其他常用选项 (Other Useful Options)
##############################################################################

ls -R                                   # 递归列出所有子目录的内容
ls -i                                   # 显示每个文件的 inode 号
ls -s                                   # 显示每个文件分配的块大小 (以块为单位，通常是 KB)
ls -n                                   # 类似 -l，但以数字 UID 和 GID 代替用户名和组名
ls -L                                   # 当列出符号链接时，显示链接指向的文件信息，而不是链接本身
ls -H                                   # (GNU) 类似 -L，但只对命令行参数中的符号链接生效
ls -Q                                   # (GNU) 将文件名用双引号括起来

##############################################################################
# 实用技巧 (Tips and Tricks)
##############################################################################

# 1. 定义常用别名 (放入 ~/.bashrc 或 ~/.zshrc):
#    alias ll='ls -lha'       # 显示所有文件(含隐藏), 长格式, 易读大小
#    alias la='ls -A'         # 显示几乎所有文件(不含.和..)
#    alias lt='ls -ltrh'      # 按时间倒序显示详细信息(最旧在前), 易读大小

# 2. 结合 `grep` 过滤结果:
#    ls -l | grep '^d'        # 仅列出目录 (基于权限字符串首字母)
#    ls -F | grep '/$'        # 仅列出目录 (基于 -F 的 / 后缀)
#    ls -l | grep 'Jan'       # 列出最后修改月份是 Jan 的文件

# 3. 结合 `head`/`tail` 查看最新/最旧文件:
#    ls -t | head -n 5        # 列出最新的 5 个文件/目录
#    ls -tr | head -n 5       # 列出最旧的 5 个文件/目录 (注意 -r 反转)

# 4. 查看文件数量:
#    ls -1 | wc -l            # 统计当前目录下的文件和目录总数 (不含隐藏)
#    ls -A1 | wc -l           # 统计当前目录下几乎所有文件和目录总数

# 5. 彩色输出通常由 `LS_COLORS` 环境变量或发行版别名配置控制。
#    可以使用 `dircolors -p > ~/.dircolors` 生成配置模板并修改。

##############################################################################
# 示例 (Examples)
##############################################################################

# 1. 显示当前目录下所有文件的详细信息，按修改时间倒序排列 (最新的在最后)，并使用易读大小
ls -ltrh

# 2. 显示 /etc 目录下所有文件和目录 (包括隐藏，但不包括 . 和 ..) 的详细信息
ls -lA /etc

# 3. 仅列出当前目录下的子目录名称 (不递归)
ls -F | grep '/$'
#   或者 (更可靠，只显示目录):
find . -maxdepth 1 -mindepth 1 -type d -printf '%f\n'

# 4. 列出当前目录中最大的 3 个文件
ls -lSh | head -n 4  # head -n 4 是因为第一行是 total

# 5. 列出当前目录所有 .log 文件，并显示 inode 号
ls -i *.log

##############################################################################
# 鸣谢 & 更多资源 (Credit & Further Resources)
##############################################################################

# GNU Coreutils `ls` manual: https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html
# 通过命令行获取帮助: `man ls` 或 `ls --help`

# vim: set ts=4 sw=4 tw=0 et ft=sh :
